<!DOCTYPE html>
<head>
<title>Experimental Random Map Generator</title>
</head>
<body>

<h1>Experimental Random Map Generator</h1>

<h2>Table of Contents</h2>
<ul>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#disclaimers">Disclaimers</a></li>
    <li><a href="#installing">Installing</a></li>
    <li><a href="#controls-and-parameters">Controls and Parameters</a></li>
    <li><a href="#about-the-source-code">About the source code</a></li>
    <li><a href="#metadata">Metadata</a></li>
</ul>

<h2 id="introduction">Introduction</h2>
<p>This is a short proof-of-concept program I wrote to see if it is feasible to
create a randomly-generated map that looks pretty (ie minimal line intersections,
no nodes overlapping, etc.)</p>

<p>For more information about how this was written, read the Wikipedia entry on 
<a href="http://en.wikipedia.org/wiki/Force-based_algorithms_%28graph_drawing%29">force-based algorithms</a>.</p>

<p>It's written in <a href="python.org">Python 2.7</a> using 
<a href="pygame.org">Pygame</a>.</p>

<h2 id="disclaimers">Disclaimers</h2>

<p>This isn't C#.  However, I tried to avoid using Python-only features or libraries so
it's easier to port to other languages.</p>

<p>The source code is awful -- it was written in a rush, it's a bit hacky, the 
variable names are somewhat inconsistent, the logic isn't perfectly sound,
the code is a bit muddled, it glitches sometimes (especially with odd parameters),
and it's not completely bug free, but it should be fairly stable, unless you
deliberately try and break it.</p>

<h2 id="installing">Installing</h2>

<p>You will need the following installed on your computer:</p>
<ul>
  <li><a href="http://python.org">Python version 2.7</a></li>
  <li><a href="http://pygame.org">Pygame (latest version)</a></li>
</ul>

<p>In addition, Pygame may prompt you to install additional modules to run.</p>

<p>The config file stays in the same directory as the source code in order for
the program to run.</p>

<h2 id="controls-and-parameters">Controls and Parameters</h2>
<h3>Controls</h3>
<ul>
    <li>Use the mouse to drag nodes around (click and drag)</li>
    <li>Hit 'R' to reload the parameters (if you changed them) without generating a 
    new map.</li>
    <li>Hit 'N' to create a new map.</li>
    <li>Hit 'F' to toggle between freezing and unfreezing the movement.</li>
</ul>

<h3>Parameters</h3>
<ul>
    <li><strong>num_nodes</strong>: the number of nodes there are.</li>
    <li><strong>max_neighbors</strong>: the maximum number of connections each node 
    can have.  This is buggy.</li>
    <li><strong>min_neighbors</strong>: the minimum number of connections each node 
    can have.  This is currently not implmented (so changing the number does 
    nothing.</li>
    <li><strong>repulsion</strong>: how strong the repelling force between each node
    is.  Any value between 100000 and 1000000 seems to work best.</li>
    <li><strong>attraction</strong>: how strong the pulling force for each connection
    is.  Any value between 0 and 10 seems to work best.</li>
    <li><strong>stable_spring_distance</strong>: The approximate length each connection
    tends to gravitate towards (in pixels).</li>
    <li><strong>timestep</strong>: the higher the number, the faster the simulation
    runs.  Any number between 0 to 0.5 works best.  If you go too high, the
    simulation errors and crashes.</li>
    <li><strong>damping</strong>: the lower the number, the faster the system will
    stabilize.  The number MUST be between 0 and 1.</li>
    <li><strong>min_energy</strong>: does nothing.</li>
</ul>

<h2 id="about-the-source-code">About the Source Code</h2>

<p>`Graph` generates a random map.  `Node` contains data pertaining to an individual
room.  It's highly integrated with `Graph`.  `Graphics` contains rendering and
graphics code.  It also contains the mainloop by accident -- it needs to be moved
out.</p>

<p>If you want a more detailed writeup, ask on Facebook and I'll spend some time
documenting the code over vacation.</p>

<h2 id="metadata">Metadata</h2>
<dl>
    <dt>Author</dt>
    <dd>Michael Lee (<a href="mailto:michael.lee.0x2a@gmail.com">michael.lee.0x2a@gmail.com</a>)</dd>
    <dt>License</dt>
    <dd>GNU Lesser GPL</dd>
    <dt>Released<dt>
    <dd>February 16th, 2012</dd>
</dl>

</body>
</html>
